home *** CD-ROM | disk | FTP | other *** search
/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / lantools / an106d / an106-4
Text File  |  1991-05-29  |  10KB  |  247 lines
  1. SPX Design Enhancements to the NetWare Requester for OS/2 (v1.3)
  2.  
  3. Bryan R. Clark 
  4. Systems Engineer 
  5. Systems Engineering Division
  6.  
  7. Robert Perry 
  8. Senior Technical Writer 
  9. Systems Engineering Division
  10.  
  11. Abstract: 
  12. This AppNote contains information for developers who write applications using 
  13. Novell's Sequenced Packet Exchange (SPX) in the OS/2 environment.  It 
  14. explains recent enhancements to SPX with the March 1991 release of the 
  15. NetWare Requester for OS/2 v1.3, including general design improvements as 
  16. well as specific changes to data structures and the Application Programming 
  17. Interface (API).  
  18.  
  19.  
  20.  
  21. Disclaimer
  22.  
  23. Novell, Inc. makes no representations or warranties with respect to the 
  24. contents or use of these Application Notes (AppNotes) or of any of the 
  25. third#party products discussed in the AppNotes. Novell reserves the right to 
  26. revise these AppNotes and to make changes in their content at any time, 
  27. without obligation to notify any person or entity of such revisions or 
  28. changes. These AppNotes do not constitute an endorsement of the third#party 
  29. product or products that were tested. Configuration(s) tested or described 
  30. may or may not be the only available solution. Any test is not a 
  31. determination of product quality or correctness, nor does it ensure 
  32. compliance with any federal, state or local requirements. Novell does not 
  33. warranty products except as stated in applicable Novell product warranties or 
  34. license agreements.
  35.  
  36. Copyright { 1991 by Novell, Inc., Provo, Utah. All rights reserved.
  37.  
  38. As a means of promoting NetWare AppNotes, Novell grants you without charge 
  39. the right to reproduce, distribute and use copies of the AppNotes, provided 
  40. you do not receive any payment, commercial benefit or other consideration for 
  41. the reproduction or distribution, or change any copyright notices appearing 
  42. on or in the document.
  43.  
  44. Contents
  45.  
  46. Introduction        55
  47.  
  48. Overview of Improvements to the OS/2 Requester        55
  49.  
  50. Design Enhancements        55
  51.  
  52. ECBs Linked to Connection        55
  53.  
  54. Problems Solved        55
  55.  
  56. SPX API Enhancements        56
  57.  
  58. Removal of the Socket-based Listen API        56
  59.  
  60. Other APIs Dropped        56
  61.  
  62. Modified APIs        57
  63.  
  64. New APIs        57
  65.  
  66. Structures Changed        57
  67.  
  68. ECB Structure Changes        57
  69.  
  70. Connection Status Structure Changes        58
  71.  
  72. SPX Throughput Increased and Memory Reduced        58
  73.  
  74. Improved Buffer Management        59
  75.  
  76. Summary of SPX Changes        60
  77.  
  78. Appendix A        61
  79.  
  80. Acknowledgements        61
  81.  
  82. Introduction
  83.  
  84. This AppNote is addressed to developers who write SPX applications that run 
  85. under OS/2.  The changes to the application programming interface (API) and 
  86. structures are explained briefly in this document.  For developers needing 
  87. more detail, an appendix at the end of the AppNote lists the Software 
  88. Developer's Kit (SDK) which includes the complete SPX specification for OS/2 
  89. workstations.
  90.  
  91. Overview of Improvements to the OS/2 Requester 
  92.  
  93. As part of the continuing effort to enhance the functionality of Novell OS/2 
  94. products, an enhanced NetWare Requester for OS/2 (v1.3) was released with 
  95. NetWare v3.11.  Release 1.3 of the Requester provides enhancements to the SPX 
  96. API, an increase in SPX throughput, a significant reduction in memory 
  97. requirements, and improved buffer management.
  98.  
  99. Design Enhancements
  100.  
  101. ECBs Linked to Connection
  102.  
  103. From its inception, SPX has always been a connection-based protocol. However, 
  104. because of the strong coupling of a socket to a connection, the two notions 
  105. became almost synonymous.  This led to the convention of linking Event 
  106. Control Blocks (ECBs) to the socket rather than the connection. The new 1.3 
  107. Requester SPX driver now links ECBs only to connections.
  108.  
  109. Problems Solved
  110.  
  111. Previously, when multiplexing both socket-based and connection-based 
  112. applications on the same socket, there were problems. First was the matching 
  113. of incoming received packets to listen ECBs. SPX could not properly determine 
  114. if the incoming packet was destined for the socket or connection. Since ECBs 
  115. are now linked only to a connection, this matching problem has been solved.
  116.  
  117. Secondly, when multiplexing on the same socket, remote machines could not 
  118. determine the number of listen ECBs available. For example, look at the 
  119. configuration shown in Figure 1. Suppose a socket on A has two connections 
  120. (one to B and one to C), and that it has posted four listen ECBs on the 
  121. socket. In this situation, B would think that there are four ECBs available, 
  122. and so would C. Thus, if both B and C wanted to send at the same time, there 
  123. would be eight incoming packets and only four listen ECBs to receive them. 
  124. Obviously, this would result in errors that require retransmission. Now that 
  125. ECBs are posted on the connection, A would post two ECBs to each connection.  
  126.  
  127.  
  128. : Old method of multiple connections on the same socket. 
  129.  
  130. By having ECBs linked to the connection rather than to a socket, the problem 
  131. of running out of listen ECBs, as described in Figure 1, is now solved as 
  132. well.
  133.  
  134. SPX API Enhancements
  135.  
  136. The SPX APIs have been updated to remove the usage of sockets where 
  137. connections should be used. Several of the APIs were modified to better 
  138. support the connection-based protocol. Other APIs were removed because their 
  139. functionality existed elsewhere. 
  140.  
  141. Removal of the Socket-based Listen API
  142.  
  143. Due to its use of the socket parameter, the SPXListenForSequencedPacket API 
  144. has been removed. It should be replaced by SPXListenForConnectionPacket, 
  145. which correctly uses a connection parameter instead of a socket for posting 
  146. ECBs.
  147.  
  148. Other APIs Dropped
  149.  
  150. Some of the APIs have been dropped because their functionality is now 
  151. provided elsewhere.  The functions of SPXGetTime can now be accessed with 
  152. DOSGetTimeAndDate.  The function of SPXCleanUp is now handled by 
  153. SPXTerminateConnection, since cleanup is now associated with a connection.
  154.  
  155. Modified APIs
  156.  
  157. Several APIs were modified to support the SPX enhancements.  Both the 
  158. SPXOpenSocket and SPXCloseSocket now return IPX error codes, which will 
  159. require IPXError.H to included.  Also note that SPX_ SUCCESSFUL has been 
  160. chaged to 0x3000.  This may require logic changes in your application's code. 
  161.  
  162.  
  163. SPXCleanup is no longer available to the application, but this functionality 
  164. has been included in the SPXTerminateConnection call.  SPXCloseSocket no 
  165. longer does clean up. Before closing a connection, a semaphore should be set 
  166. and SPXTerminateConnection called. Once the semaphore is cleared, you can 
  167. call SPXCloseSocket.  In a more minor change, SPXGetVersion no longer returns 
  168. revDate; the revision date can now be obtained by using NVER.EXE.
  169.  
  170. New APIs
  171.  
  172. With the changes in SPX, new APIs have been introduced.  The first of these, 
  173. SPXECBErrorCheck, enables or disables extensive error checking on ECBs, 
  174. including extensive listings of errors encountered.  
  175.  
  176. An additional pair of APIs, SPXEstablishConnection2 and 
  177. SPXListenForConnection2, introduce the new ListenECB parameter.  These APIs 
  178. ensure that a listen ECB is preposted to a connection before it is 
  179. established.  Previously, if a remote partner was trying to send, SPX would 
  180. block the send waiting for a listen ECB to be posted.  With the new APIs the 
  181. first packet can be sent immediately after establishing the connection.  This 
  182. also reduces the number of LSL buffers used and minimizes SPX timeouts or 
  183. retransmitions. 
  184.  
  185. Structures Changed
  186.  
  187. ECB Structure Changes
  188.  
  189. The ECB structure itself has been modified. Minor changes involved moving 
  190. HSEM from its position in the ECB's Reserved structure (at offset 10) to its 
  191. own place at offset 34 (the Reserved structure remains in place for future 
  192. use), and removing Connection Number from the ECB's Protocol Workspace 
  193. structure.  Figure 2 shows the old and new ECB structure.
  194.  
  195. : The SPX Event Control Block structure, before and after modification    
  196.  
  197. Connection Status Structure Changes
  198.  
  199. The structure of SPXGetConnectionStatus has also been changed.  The 
  200. LocalSocket (offset 32) and SupressedPackets (offset 54) fields were deleted. 
  201.  The RemoteSequenceNumber was added (at offset 12) to facilitate buffer 
  202. management.  Also, the RetransmitCount was renamed to RetryCount (offset 44). 
  203.  Figure 3 shows the old and the new versions of the SPXGetConnectionStatus 
  204. structure.
  205.  
  206. SPX Throughput Increased and Memory Reduced
  207.  
  208. The new SPX provides an increase in performance. It also minimizes the use of 
  209. LSL buffers and simplifies the LSL buffer management. The amount of memory 
  210. required to load the SPX driver has been reduced to a fraction of what it 
  211. used to be.
  212.  
  213. : The SPXGetConnectionStatus structure, before and after modificiation 
  214.  
  215. Improved Buffer Management
  216.  
  217. During an SPX call, the memory segment containing the ECB buffer is now 
  218. locked, preventing relocation of memory. An application must not change the 
  219. ECB fields while an SPX call is being made. The application should use a 
  220. semaphore to wait for the completion of the SPX call.  Alternatively, by 
  221. passing a NULL for the ECB semaphore handle and polling the ECBStatus field, 
  222. an OS/2 application can determine when the SPX call has completed.
  223.  
  224. Summary of SPX Changes
  225.  
  226. This section is included as a brief listing of all the key SPX- related 
  227. changes involved in release 1.3 of the NetWare Requester for OS/2. 
  228.  
  229.  
  230.  
  231. Appendix A
  232.  
  233. To obtain the latest Software Developer's Kit (SDK), call Novell Developer 
  234. Relations at 1-800-RED-WORD (1-800-733-9673). The part numbers are listed 
  235. below:
  236.  
  237. 1.3 OS/2 Requester SDK (5 1/4-inch diskettes)  Part Number 883-000940-001 
  238. 1.3 OS/2 Requester SDK (3 1/2-inch diskettes)  Part Number 883-000941-001
  239.  
  240. Acknowledgements
  241.  
  242. A special thanks to Bob Young and Mike Lasky for their help with this 
  243. AppNote.  
  244.  
  245. Editor's Note: The author accepts written feedback at FAX (801) 429#5511.
  246.  
  247.